Skip to content

docs: add AEO cross-links for agents and orchestration#265

Closed
rachaelrenk wants to merge 2 commits into
mainfrom
docs/aeo-crosslinks-agents-orchestration-2026-06-29
Closed

docs: add AEO cross-links for agents and orchestration#265
rachaelrenk wants to merge 2 commits into
mainfrom
docs/aeo-crosslinks-agents-orchestration-2026-06-29

Conversation

@rachaelrenk

@rachaelrenk rachaelrenk commented Jun 29, 2026

Copy link
Copy Markdown
Contributor

AEO cross-link audit

Small, high-confidence internal cross-links for agents, cloud agents, and orchestration docs, sourced from the Peec AEO snapshot (buzz/aeo-snapshots/docs/agents-orchestration/latest.json, generated 2026-06-24).

Goal

Identify small internal cross-link improvements for agents, cloud agents, and orchestration docs so readers can jump from an overview/concept page to the canonical page for the workflow they're researching.

Source signals

Top Peec prompt clusters this period (all high or medium volume):

  • "how do I set up AI coding agents to run on a schedule or in the background?" (scheduling, high volume)
  • "how do I run multiple AI coding agents in parallel?" / "best tools for managing multiple AI coding agents" (parallel/multi-agent, high/medium volume)
  • "how do I trigger AI coding agents automatically from Slack, Linear, or GitHub?" (integration triggers, high volume)

Pages touched

  • src/content/docs/agent-platform/getting-started/agents-in-warp.mdx — the "From local to cloud" section names scheduling and parallel execution but only linked to the cloud agents overview.
  • src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx — the "Common ways to trigger" list named first-party integrations (Slack, Linear) without linking to the integrations docs.

Links added

  • agents-in-warp.mdx → Scheduled Agents — anchored on "schedules" in the "Run on schedules for recurring tasks" bullet. Backed by the high-volume scheduling prompt cluster.
  • agents-in-warp.mdx → Multi-agent orchestration — anchored on "in parallel across repos or tasks". Backed by the parallel/multi-agent prompt clusters.
  • deployment-patterns.mdx → Integrations overview — appended to the "First-party integrations (Slack, Linear, etc.)" trigger bullet. Backed by the Slack/Linear/GitHub trigger prompt cluster.

Reader next step

  • A reader on the getting-started agents hub who is interested in running agents on a recurring cadence or fanning work out in parallel can go straight to the scheduling and orchestration docs instead of routing through the cloud agents overview.
  • A reader comparing deployment patterns who wants event-driven triggers can jump to the integrations setup docs from the pattern that mentions them.

Open questions for human review

  • The "From local to cloud" section also lists "React to events from Slack, Linear, or GitHub". I linked integrations from deployment-patterns.mdx instead to keep agents-in-warp.mdx to two new links; reviewers may prefer also linking integrations directly on that bullet.
  • Newer signals this period (SSH-based remote agent access, self-hosted/on-prem) had no clear high-confidence existing-docs target and were left as follow-ups.

Follow-up recommendations (out of scope for this cross-link pilot)

  • Consider whether an SSH/remote-terminal-with-agents page is warranted given the new SSH signal.
  • Evaluate whether self-hosted/on-prem queries should cross-link to environment isolation / self-hosting docs more prominently.

Conversation: https://app.warp.dev/conversation/1605300e-6a83-496f-9ccd-32d244d6df5d
Run: https://oz.warp.dev/runs/019f13e4-fb3c-7d09-843f-46e4742674de

This PR was generated with Oz.

@rachaelrenk @oz-agent
docs: add AEO cross-links for agents and orchestration
56ea004 
Co-Authored-By: Oz <oz-agent@warp.dev>
@cla-bot cla-bot Bot added the cla-signed label Jun 29, 2026
@vercel

vercel Bot commented Jun 29, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
docs Ready Ready Preview, Comment Jun 30, 2026 5:25pm

Request Review

@rachaelrenk rachaelrenk self-assigned this Jun 29, 2026
@rachaelrenk rachaelrenk marked this pull request as ready for review June 29, 2026 21:14
@oz-for-oss

oz-for-oss Bot commented Jun 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

@rachaelrenk

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss[bot]
oz-for-oss Bot reviewed Jun 29, 2026
View reviewed changes

@oz-for-oss oz-for-oss Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overview

This PR adds three targeted internal links that connect agent overview and deployment-pattern content to the canonical Scheduled Agents, multi-agent orchestration, and integrations pages. The linked destinations exist in the docs tree, the changes are scoped to existing AEO/source-data rationale, and the diff does not introduce code or configuration security concerns.

Concerns

  • No blocking concerns found.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

@rachaelrenk rachaelrenk mentioned this pull request Jul 1, 2026
Merged
@rachaelrenk

rachaelrenk commented Jul 1, 2026

Copy link
Copy Markdown
Contributor Author

Closing this out — the docs were restructured in #262 (merged 2026-06-30), which moved agent-platform/cloud-agents/* to the new top-level platform/* section. As a result, this PR:

  • edits agent-platform/cloud-agents/deployment-patterns.mdx, which has moved to platform/deployment-patterns.mdx, and
  • links to /agent-platform/cloud-agents/{orchestration, triggers/scheduled-agents, integrations} routes, which now only exist as redirects (the skill requires linking to the final destination).

Rather than hand-rebase a small, auto-generated cross-link PR, I'm closing it. The aeo_crosslink_audit skill has been hardened in #280 to re-validate edited files and link targets against the latest main and resolve redirects before opening a PR, so the next biweekly run will regenerate these links correctly against the new platform/ structure.

Resolved as part of an Oz-assisted review of the AEO cross-link workflow.

@rachaelrenk rachaelrenk closed this Jul 1, 2026
rachaelrenk added a commit that referenced this pull request Jul 2, 2026
@rachaelrenk @oz-agent @oz-for-oss
docs(skills): make aeo_crosslink_audit reliable (#280)
1064dcf 
* docs(skills): make aeo_crosslink_audit reliable + set biweekly cadence

Assessment of the scheduled AEO cross-link agent found the run log has
never populated and several noise sources in the automated PRs. Fixes:

- Run logging: never commit to protected main (direct commits failed
  silently, leaving the log empty and blocking improve-aeo-crosslink-skill).
  Use a standing chore/aeo-crosslink-audit-log branch + one perpetual PR.
- Dedup/supersede: check for an existing open cross-link PR before opening;
  never leave two open at once (prevents duplicates like #232 vs #228).
- Low-signal runs: prefer a no-change report over weak docs-only PRs when
  neither Peec nor GSC signals are usable.
- Restructure-safety: re-validate edited files and link targets against the
  latest main and resolve redirects before opening (prevents #262/#265-style
  breakage where cloud-agents moved to platform/).
- Document biweekly cadence.
- improve-skill: note the standing log PR must be merged before analysis.

Co-Authored-By: Oz <oz-agent@warp.dev>

* docs(skills): align documented biweekly cron with live 15:00 UTC run time

Co-Authored-By: Oz <oz-agent@warp.dev>

* docs(skills): drop biweekly Schedule section; keep weekly cadence

Co-Authored-By: Oz <oz-agent@warp.dev>

* Update .agents/skills/aeo_crosslink_audit/SKILL.md

Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>

---------

Co-authored-by: Oz <oz-agent@warp.dev>
Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@oz-for-oss oz-for-oss[bot] oz-for-oss[bot] left review comments

Assignees

@rachaelrenk rachaelrenk

Labels

cla-signed

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@rachaelrenk